TeamDynamix MCP
🎟️ TeamDynamix MCP Server (unofficial)
A TypeScript Model Context Protocol (MCP) server that exposes TeamDynamix ITSM capabilities as agent-callable tools. Designed for AI agents and MCP clients that need structured, safety-gated access to TeamDynamix operations.
Features
- 11 domain gateway tools that route validated actions across discovery, tickets, relationships, KB, assets, CMDB, people, services, projects, time, and reference data
- Safe by default: write tools disabled until explicitly opted in;
destructive operations require
confirm: true - Two auth modes: standard (username/password) and admin (BEID/WebServicesKey)
- Rate-limit aware: auto-retry with backoff on 429 responses
- Zod-validated inputs: schema enforcement before any API call
- Agent skill and prompt included: ready-to-use skill definition for GitHub Copilot and compatible agents
Minimum required environment variables
TEAMDYNAMIX_BASE_URL=https://your-tenant.teamdynamix.com/TDWebApi
TEAMDYNAMIX_AUTH_MODE=standard # or: admin
TEAMDYNAMIX_USERNAME=you@example.com # standard mode
TEAMDYNAMIX_PASSWORD=your-password # standard mode
For admin mode, use TEAMDYNAMIX_BEID and TEAMDYNAMIX_WEB_SERVICES_KEY instead.
MCP client configuration
Security notice: Values shown above are placeholders. Never commit real credentials to source control. Inject secrets at runtime via a
.envfile (excluded by.gitignore), CI/CD secrets, or a secret manager.
VS Code (.vscode/mcp.json)
{
"servers": {
"teamdynamix": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@selfagency/teamdynamix-mcp"],
"env": {
"TEAMDYNAMIX_BASE_URL": "https://your-tenant.teamdynamix.com/TDWebApi",
"TEAMDYNAMIX_AUTH_MODE": "standard",
"TEAMDYNAMIX_USERNAME": "you@example.com",
"TEAMDYNAMIX_PASSWORD": "your-password"
}
}
}
}
Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"teamdynamix": {
"command": "npx",
"args": ["-y", "@selfagency/teamdynamix-mcp"],
"env": {
"TEAMDYNAMIX_BASE_URL": "https://your-tenant.teamdynamix.com/TDWebApi",
"TEAMDYNAMIX_AUTH_MODE": "standard",
"TEAMDYNAMIX_USERNAME": "you@example.com",
"TEAMDYNAMIX_PASSWORD": "your-password"
}
}
}
}
Production (built bundle)
pnpm build # outputs to dist/
{
"command": "npx",
"args": ["-y", "@selfagency/teamdynamix-mcp"]
}
Verify connectivity
After connecting your MCP client, call teamdynamix_discovery with:
action: "server_status"payload: {}response_format: "json"
A successful response shows status.configured: true.
Domain gateway tools
Each gateway tool accepts:
action: domain-specific operation namepayload: object for that action’s parametersresponse_format:"markdown"or"json"
| Domain | Gateway tool |
|---|---|
| Discovery | teamdynamix_discovery |
| Tickets | teamdynamix_tickets |
| Ticket relationships | teamdynamix_ticket_relationships |
| Knowledge Base | teamdynamix_knowledge_base |
| Assets | teamdynamix_assets |
| CMDB | teamdynamix_cmdb |
| People | teamdynamix_people |
| Services | teamdynamix_services |
| Projects | teamdynamix_projects |
| Time | teamdynamix_time |
| Reference data | teamdynamix_reference_data |
† Requires confirm: true in addition to write tools being enabled.
All write/mutating actions require TEAMDYNAMIX_ENABLE_WRITE_TOOLS=true.
Safety defaults
| Flag | Default | Effect when true |
|---|---|---|
TEAMDYNAMIX_ENABLE_WRITE_TOOLS | false | Enables all create/update/comment/mutation tools |
TEAMDYNAMIX_ENABLE_ADMIN_TOOLS | false | Enables admin-scope operations |
Destructive unlink operations additionally require confirm: true in the
tool call regardless of write flag state.
Agent skill
This repository ships a GitHub Copilot-compatible skill definition:
- Skill:
skills/teamdynamix/SKILL.md— ID-first workflow patterns, safety branching rules, runbooks, gotchas, and tool catalog - Agent prompt:
prompts/teamdynamix-agent.prompt.md— system prompt for agent mode with TeamDynamix context
Install the skill via your Copilot skill configuration
(see skills/teamdynamix/SKILL.md for full details).
Documentation
| Section | Purpose |
|---|---|
| Tutorials | Step-by-step setup and first workflows |
| How-to guides | Task-oriented recipes for real operations |
| Reference | Exhaustive tool catalog, configuration, safety model, errors |
| Explanation | Architecture, auth model, safety rationale, rate limiting |
| Development | Architecture, contributing, testing |
License
MIT © The Self Agency LLC
Server Config
{
"mcpServers": {
"git": {
"command": "npx",
"args": [
"-y",
"@selfagency/teamdynamix-mcp"
],
"env": {
"TEAMDYNAMIX_BASE_URL": "https://your-tenant.teamdynamix.com",
"TEAMDYNAMIX_AUTH_MODE": "standard",
"TEAMDYNAMIX_USERNAME": "your-username",
"TEAMDYNAMIX_PASSWORD": "your-password-preferably-stored-securely"
}
}
}
}